<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>libdill</title>
  <link rel="stylesheet" type="text/css" href="main.css">
</head>
<body>

<h1>libdill: Structured Concurrency for C</h1>

<ul id='toplist'>
<li><a href="index.html">Home</a></li>
<li><a href="download.html">Download</a></li>
<li><a href="documentation.html">Documentation</a></li>
<li><a href="tutorial.html">Tutorials</a></li>
<li><a href="faq.html">FAQ</a></li>
</ul>
<h1 id="frequently-asked-questions">Frequently Asked Questions</h1>
<h5 id="how-can-i-report-a-bug">How can I report a bug?</h5>
<p>Report a bug here:</p>
<p><a href="https://github.com/sustrik/libdill/issues" class="uri">https://github.com/sustrik/libdill/issues</a></p>
<h5 id="whats-structured-concurrency">What's structured concurrency?</h5>
<p>Check this short introductory <a href="structured-concurrency.html">article</a> about structured concurrency.</p>
<h5 id="whats-libdills-performance">What's libdill's performance?</h5>
<p>The best way to find out is to check for yourself. You will find some small performance benchmarks in the <code>perf</code> subdirectory.</p>
<p>Generally speaking, though, libdill's concurrency primitives are only a bit slower than basic C flow control statements. A context switch has been seen to execute in as little as 6 ns, with coroutine creation taking 26 ns. Passing a message through a channel takes about 40 ns.</p>
<h5 id="how-does-libdills-concurrency-differ-from-gos-concurrency">How does libdill's concurrency differ from Go's concurrency?</h5>
<ol>
<li>No interaction between threads. Each thread is treated as a separate process.</li>
<li>Channels are always unbuffered.</li>
<li><code>choose</code>, unlike <code>select</code>, is deterministic. If multiple clauses can be executed, the clause closest to the beginning of the pollset wins.</li>
<li><code>chdone</code> signals the closing of a channel to both senders and receivers.</li>
<li>Coroutines can be canceled.</li>
</ol>
<h5 id="how-does-libdill-differ-from-libmill">How does libdill differ from libmill?</h5>
<p><code>libmill</code> was a project that aimed to copy Go's concurrency model to C 1:1 without introducing any innovations or experiments. The project is finished now. It will be maintained but won't change in the future.</p>
<p><code>libdill</code> is a follow-up project that experiments with structured concurrency and diverges from the Go model.</p>
<p>Technically, these are the differences:</p>
<ol>
<li>Libdill is idiomatic C. Whereas libmill takes Go's concurrency API and implements it in an almost identical manner in C, libdill tries to provide the same functionality via a more C-like and POSIX-like API. For example, <code>choose</code> is a function in libdill rather than a language construct, or Go's panic is replaced with error returns.</li>
<li>Coroutines can be canceled. This creates a foundation for &quot;structured concurrency&quot;.</li>
<li><code>chdone</code> causes blocked <code>recv</code> on the channel to return the <code>EPIPE</code> error rather than a value.</li>
<li><code>chdone</code> will signal both the senders and the receivers of a channel. This allows for scenarios such as multiple senders and a single receiver communicating via a single channel. The receiver can use <code>chdone</code> to let the senders know that it's terminating.</li>
<li>libmill's <code>fdwait</code> was replaced by <code>fdin</code> and <code>fdout</code>. The idea is that if we want data to flow through the connection in both directions in parallel, we should use two coroutines rather than one.</li>
</ol>
<h5 id="i-experience-name-clashes-with-libdill.-how-do-i-avoid-that">I experience name clashes with libdill. How do I avoid that?</h5>
<p>Define <code>DILL_DISABLE_RAW_NAMES</code> before including <code>libdill.h</code>. All the symbols defined by libdill will be prefixed by <code>dill_</code>. For example: <code>dill_go</code>, <code>struct dill_iolist</code> or <code>DILL_WS_TEXT</code>.</p>
<h5 id="how-can-i-access-the-source-code">How can I access the source code?</h5>
<p>To clone the repository, run:</p>
<pre><code>$ git clone https://github.com/sustrik/libdill.git</code></pre>
<p>To build from the source (you'll need automake and libtool), run:</p>
<pre><code>$ ./autogen.sh
$ ./configure
$ make
$ make check
$ sudo make install</code></pre>
<p>For easy debugging, use the following configure options:</p>
<pre><code>$ ./configure --disable-shared --enable-debug --enable-valgrind</code></pre>
<p>The above will turn optimization off, generate debug symbols, and link all the tests with the static version of the library. The second option will cause executables in the <code>tests</code> subdirectory to be actual debuggable binaries rather that wrapper shell scripts. The last option instructs valgrind about where the coroutine stacks are located, thereby preventing valgrind from generating spurious warnings.</p>
<h5 id="is-continuous-integration-available-for-libdill">Is continuous integration available for libdill?</h5>
<iframe width="100%" height="20" frameBorder="0"
src="https://api.travis-ci.org/sustrik/libdill.svg?branch=master">
</iframe>
<p>Travis: <a href="https://travis-ci.org/sustrik/libdill" class="uri">https://travis-ci.org/sustrik/libdill</a></p>
<h5 id="how-can-i-contribute">How can I contribute?</h5>
<p>To contribute to libdill, create a GitHub pull request. You have to state that your patch is submitted under the MIT/X11 license, so that it can be incorporated into the mainline codebase without licensing issues.</p>
<p>If you make a substantial contribution to a file, add your copyright to the file header. Irrespective of whether you do so or not, your name will be added to the AUTHORS file to indicate you own copyright to part of the codebase.</p>
<h5 id="how-can-i-see-coverage-report-for-the-tests">How can I see coverage report for the tests?</h5>
<pre><code>$ ./configure --enable-gcov
$ make clean
$ make check
$ lcov -t &quot;libdill&quot; -o libdill.info -c -d .
$ genhtml -o lcov libdill.info</code></pre>
<p>After doing the steps above open <code>lcov/index.html</code> in your browser.</p>
<h5 id="how-are-the-man-pages-generated">How are the man pages generated?</h5>
<p>The source for all the man pages is <code>man/manpages.src</code>. If you want to fix the man pages edit that file.</p>
<p>To generate actual man pages from the source you'll need <code>nodejs</code> and <code>pandoc</code>. Do the following:</p>
<pre><code>$ cd man
$ ./generate.sh</code></pre>
<p>Generated man pages are added to the git repository so that they are available even for users without the appropriate toolchain installed.</p>
<h5 id="how-is-the-website-generated">How is the website generated?</h5>
<p>The source for the website is in <code>website/src</code> directory. The source for man pages is in <code>man/manpages.src</code>.</p>
<p>To generate the acutal website you'll need <code>nodejs</code> and <code>pandoc</code>. Do the following:</p>
<pre><code>$ cd website
$ ./generate.sh</code></pre>
<p>Generated HTML pages are added to the git repository so that they are available even for users without the appropriate toolchain installed.</p>
<h5 id="what-is-the-release-process">What is the release process?</h5>
<p>These instructions are intended for project maintainers:</p>
<ul>
<li>Make sure that documentation is up-to-date.</li>
<li>Adjust <code>download.md</code> and <code>libdill-history.md</code> in <code>website/src</code> directory.</li>
<li>Regenerate the website: <code>cd website; ./generate.sh</code>.</li>
<li>Submit the changes.</li>
<li>Run <code>make distcheck</code> to check whether the packaging process still works.</li>
<li>Bump the ABI version appropriately (see here: <a href="http://250bpm.com/blog:41" class="uri">http://250bpm.com/blog:41</a>).</li>
<li>Commit and push your commits back to the master branch on GitHub.</li>
<li>Tag the new version and push the tag to GitHub (e.g. <code>git tag -a 2.8; git push origin 2.8</code>).</li>
<li>Clone a clean repo from GitHub.</li>
<li>Build the package (<code>./autogen.sh; ./configure; make distcheck</code>).</li>
<li>Add the package to the <code>gh-pages</code> branch.</li>
<li>Copy the website from the master branch: <code>./publish.sh</code>.</li>
<li>Commit and push to <code>gh-pages</code>.</li>
<li>Announce the release on twitter, etc.</li>
</ul>
</body>
